Skip to content

Comments

docs: restructure documentation around user journey#609

Merged
bug-ops merged 3 commits intomainfrom
docs/rethink-structure
Feb 19, 2026
Merged

docs: restructure documentation around user journey#609
bug-ops merged 3 commits intomainfrom
docs/rethink-structure

Conversation

@bug-ops
Copy link
Owner

@bug-ops bug-ops commented Feb 19, 2026

Summary

  • Reorganize docs from feature-oriented flat list (26 guide pages) to progressive disclosure structure: Introduction -> Core Concepts -> Guides -> Advanced -> Reference
  • Rewrite introduction as value proposition instead of feature dump
  • Add "Why Zeph?" page with differentiators (token efficiency, hybrid inference, privacy)
  • Replace Quick Start with scenario-driven "First Conversation" onboarding
  • Add Core Concepts section (skills, memory, providers, tools) as gentle entry point
  • Split guides into scenario-based (cloud provider, Telegram, custom skills) and deep dives (advanced/)
  • Merge related pages: audio+vision -> multimodal, daemon+scheduler -> daemon
  • Move reference material (CLI, config, feature flags, security) to dedicated Reference section
  • Update all internal cross-references

Test plan

  • mdbook build passes with no errors or warnings
  • All internal links resolve correctly
  • New user can follow Introduction -> First Conversation -> Core Concepts path
  • Existing deep-dive content preserved in Advanced section

Reorganize docs from feature-oriented flat list to progressive
disclosure structure (attract -> onboard -> deepen -> master).

New pages:
- introduction.md: value proposition instead of feature dump
- why-zeph.md: differentiators and advantages
- first-conversation.md: scenario-driven onboarding
- wizard.md: focused zeph init walkthrough
- concepts/: skills, memory, providers, tools overviews
- guides/: cloud-provider, telegram, custom-skills

Structure changes:
- guide/ (26 flat pages) -> advanced/, guides/, concepts/, reference/
- Merged: audio-input+vision -> multimodal, daemon+scheduler -> daemon
- Split: configuration -> wizard + reference, channels -> telegram guide + full reference
- All internal cross-references updated
@github-actions github-actions bot added documentation Improvements or additions to documentation size/XL labels Feb 19, 2026
@bug-ops bug-ops enabled auto-merge (squash) February 19, 2026 16:37
@bug-ops bug-ops merged commit b727a0b into main Feb 19, 2026
22 checks passed
@bug-ops bug-ops deleted the docs/rethink-structure branch February 19, 2026 16:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size/XL

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant